---
title: 旁白
description: 了解如何在 Starlight 中使用旁白，从而在页面的主要内容旁边显示次要信息。
---

import { Aside } from '@astrojs/starlight/components';

要在页面的主要内容旁边显示次要信息，请使用 `<Aside>` 组件。

import Preview from '~/components/component-preview.astro';

<Preview>

<Aside slot="preview">
    在 `<Aside>` 中包含非必要的补充信息。
</Aside>

</Preview>

## 导入

```tsx
import { Aside } from '@astrojs/starlight/components';
```

## 用法

使用 `<Aside>` 组件以显示旁白（也称为“警告”或“标注”）。

`<Aside>` 有一个可选的 [`type`](#type) 属性，它控制着旁白的颜色、图标和默认标题。

<Preview>

````mdx
import { Aside } from '@astrojs/starlight/components';

<Aside>一些在旁白中的内容。</Aside>

<Aside type="caution">一些警示内容。</Aside>

<Aside type="tip">

旁白中还支持其他内容。

```js
// 例如，代码片段。
```

</Aside>

<Aside type="danger">不要将你的密码告诉任何人。</Aside>
````

<Fragment slot="markdoc">

````markdoc
{% aside %}
一些在旁白中的内容。
{% /aside %}

{% aside type="caution" %}
一些警示内容。
{% /aside %}

{% aside type="tip" %}
旁白中还支持其他内容。

```js
// 例如，代码片段。
```
{% /aside %}

{% aside type="danger" %}
不要将你的密码告诉任何人。
{% /aside %}
````

</Fragment>

<Fragment slot="preview">

    <Aside>一些在旁白中的内容。</Aside>

    <Aside type="caution">一些警示内容。</Aside>

    <Aside type="tip">

    旁白中还支持其他内容。

    ```js
    // 例如，代码片段。
    ```

    </Aside>

    <Aside type="danger">不要将你的密码告诉任何人。</Aside>

</Fragment>

</Preview>

Starlight 还提供了用于在 Markdown 和 MDX 中渲染旁白的自定义语法，以此作为 `<Aside>` 组件的替代方案。
有关自定义语法的详细信息，请参阅 [“在 Markdown 中创作内容”](/zh-cn/guides/authoring-content/#旁白) 指南。

### 使用自定义标题

使用 [`title`](#title) 属性覆盖默认的旁白标题。

<Preview>

```mdx 'title="当心！"'
import { Aside } from '@astrojs/starlight/components';

<Aside type="caution" title="当心！">
	*带有* 自定义标题的警告。
</Aside>
```

<Fragment slot="markdoc">

```markdoc 'title="当心！"'
{% aside type="caution" title="当心！" %}
*带有* 自定义标题的警告。
{% /aside %}
```

</Fragment>

<Aside slot="preview" type="caution" title="当心！">
	*带有* 自定义标题的警告。
</Aside>

</Preview>

## `<Aside>` 的属性

**实现：** [`Aside.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/Aside.astro)

`<Aside>` 组件接受以下属性：

### `type`

**类型：** `'note' | 'tip' | 'caution' | 'danger'`  
**默认值：** `'note'`

要显示的旁白类型：

- `note` 旁白（默认）为蓝色，并带有一个信息的图标。
- `tip` 旁白为紫色，并带有一个火箭的图标。
- `caution` 旁白为黄色，并带有一个三角警示图标。
- `danger` 旁白为红色。并带有一个八边形警示图标。

### `title`

**类型：** `string`

要显示的旁白的标题。
如果未设置 `title`，则将使用当前旁白的 `type` 作为默认标题。
